<?php
/**
 *+------------------
 * Lflow
 *+------------------
 * Copyright (c) 2023~2030 gitee.com/liu_guan_qing All rights reserved.本版权不可删除，侵权必究
 *+------------------
 * Author: Mr.April(405784684@qq.com)
 *+------------------
 */
declare (strict_types=1);

namespace lflow;

use lflow\access\Page;
use lflow\access\QueryFilter;
use lflow\entity\HistoryOrder;
use lflow\entity\HistoryTask;
use lflow\entity\Order;
use lflow\entity\Task;

/**
 * 流程相关查询服务
 *
 * @author Mr.April
 * @since  1.0
 */
interface IQueryService
{
    /**
     * getOrder  根据流程实例ID获取流程实例对象
     *
     * @param string $orderId 流程实例id
     *
     * @return \lflow\entity\Order
     */
    public function getOrder(string $orderId): ?Order;

    /**
     * getHistOrder  根据流程实例ID获取历史流程实例对象
     *
     * @param string $orderId 历史流程实例id
     *
     * @return \lflow\entity\HistoryOrder
     */
    public function getHistOrder(string $orderId): ?HistoryOrder;

    /**
     * getTask  根据任务ID获取任务对象
     *
     * @param string $taskId 任务id
     *
     * @return \lflow\entity\Task
     */
    public function getTask(string $taskId): ?Task;

    /**
     * getHistTask  根据任务ID获取历史任务对象
     *
     * @param string $taskId
     *
     * @return \lflow\entity\HistoryTask
     */
    public function getHistTask(string $taskId): ?HistoryTask;

    /**
     * getTaskActorsByTaskId  根据任务ID获取活动任务参与者数组
     *
     * @param string $taskId
     *
     * @return array
     */
    public function getTaskActorsByTaskId(string $taskId): array;

    /**
     * getHistoryTaskActorsByTaskId  根据任务ID获取历史任务参与者数组
     *
     * @param string $taskId
     *
     * @return array
     */
    public function getHistoryTaskActorsByTaskId(string $taskId): array;

    /**
     * getActiveTasks  根据filter查询活动任务
     *
     * @param \lflow\access\QueryFilter $filter
     * @param \lflow\access\Page|null   $page
     *
     * @return array
     */
    public function getActiveTasks(QueryFilter $filter, Page|null $page): array;

    /**
     * getActiveOrders  根据filter查询流程实例列表
     *
     * @param \lflow\access\QueryFilter $filter
     * @param \lflow\access\Page|null   $page
     *
     * @return array
     */
    public function getActiveOrders(QueryFilter $filter, Page|null $page): array;

    /**
     * getHistoryOrders  根据filter查询历史流程实例
     *
     * @param \lflow\access\QueryFilter $filter
     * @param \lflow\access\Page|null   $page
     *
     * @return array
     */
    public function getHistoryOrders(QueryFilter $filter, Page|null $page = null): array;

    /**
     * getHistoryTasks  根据filter查询所有已完成的任务
     *
     * @param \lflow\access\QueryFilter $filter
     * @param \lflow\access\Page|null   $page
     *
     * @return array
     */
    public function getHistoryTasks(QueryFilter $filter, Page|null $page = null): array;

    /**
     * getWorkItems  根据filter分页查询工作项（包含process、order、task三个实体的字段集合）
     *
     * @param \lflow\access\QueryFilter $filter
     * @param \lflow\access\Page|null   $page
     *
     * @return array
     */
    public function getWorkItems(QueryFilter $filter, Page|null $page = null): array;

    /**
     * getCCWorks  根据filter分页查询抄送工作项（包含process、order）
     *
     * @param \lflow\access\QueryFilter $filter
     * @param \lflow\access\Page|null   $page
     *
     * @return array
     */
    public function getCCWorks(QueryFilter $filter, Page|null $page = null): array;

    /**
     * getHistoryWorkItems  根据filter分页查询已完成的历史任务项
     *
     * @param \lflow\access\QueryFilter $filter
     * @param \lflow\access\Page|null   $page
     *
     * @return array
     */
    public function getHistoryWorkItems(QueryFilter $filter, Page|null $page = null): array;

    /**
     * nativeQueryObject  根据类型T、Sql语句、参数查询单个对象
     *
     * @param String $sql  sql语句
     * @param array  $args 参数列表
     */
    public function nativeQueryObject(string $clazz, string $sql, array $args): object|null;

    /**
     * nativeQueryList  根据类型Sql语句、参数查询列表对象
     *
     * @param string $clazz
     * @param string $sql  sql语句
     * @param array  $args 参数列表
     *
     * @return array
     */
    public function nativeQueryList(string $clazz, string $sql, array $args): array;
}